/*
 * Copyright 2002-2012 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import org.springframework.beans.BeanMetadataElement;
import org.springframework.util.Assert;
import org.springframework.util.ObjectUtils;
import org.springframework.util.StringUtils;

/**
 * Holder for a BeanDefinition with name and aliases.
 * Can be registered as a placeholder for an inner bean.
 *
 * <p>Can also be used for programmatic registration of inner bean
 * definitions. If you don't care about BeanNameAware and the like,
 * registering RootBeanDefinition or ChildBeanDefinition is good enough.
 *
 * Bean定义的存储器
 * 它保存了Bean名称和一系列的别名
 * 如果你不关注BeanNameAware，那么注册RootBeanDefinition和ChildBeanDefinition就已经足够了
 *
 * @author Juergen Hoeller
 * @since 1.0.2
 * @see org.springframework.beans.factory.BeanNameAware
 * @see org.springframework.beans.factory.support.RootBeanDefinition
 * @see org.springframework.beans.factory.support.ChildBeanDefinition
 */
public class BeanDefinitionHolder implements BeanMetadataElement {

    /**
     * Bean定义
     */
    private final BeanDefinition beanDefinition;

    /**
     * Bean名称
     */
    private final String beanName;

    /**
     * 别名数组
     */
    private final String[] aliases;


    /**
     * Create a new BeanDefinitionHolder.
     *
     * 构造方法
     *
     * @param beanDefinition the BeanDefinition to wrap
     * @param beanName the name of the bean, as specified for the bean definition
     */
    public BeanDefinitionHolder(BeanDefinition beanDefinition, String beanName) {
        this(beanDefinition, beanName, null);
    }

    /**
     * Create a new BeanDefinitionHolder.
     *
     * 构造方法
     *
     * @param beanDefinition the BeanDefinition to wrap
     * @param beanName the name of the bean, as specified for the bean definition
     * @param aliases alias names for the bean, or {@code null} if none
     */
    public BeanDefinitionHolder(BeanDefinition beanDefinition, String beanName, String[] aliases) {
        Assert.notNull(beanDefinition, "BeanDefinition must not be null");
        Assert.notNull(beanName, "Bean name must not be null");
        this.beanDefinition = beanDefinition;
        this.beanName = beanName;
        this.aliases = aliases;
    }

    /**
     * Copy constructor: Create a new BeanDefinitionHolder with the
     * same contents as the given BeanDefinitionHolder instance.
     * <p>Note: The wrapped BeanDefinition reference is taken as-is;
     * it is {@code not} deeply copied.
     *
     * 构造方法
     *
     * @param beanDefinitionHolder the BeanDefinitionHolder to copy
     */
    public BeanDefinitionHolder(BeanDefinitionHolder beanDefinitionHolder) {
        Assert.notNull(beanDefinitionHolder, "BeanDefinitionHolder must not be null");
        this.beanDefinition = beanDefinitionHolder.getBeanDefinition();
        this.beanName = beanDefinitionHolder.getBeanName();
        this.aliases = beanDefinitionHolder.getAliases();
    }


    /**
     * Return the wrapped BeanDefinition.
     *
     * 获取Bean定义
     */
    public BeanDefinition getBeanDefinition() {
        return this.beanDefinition;
    }

    /**
     * Return the primary name of the bean, as specified for the bean definition.
     *
     * 获取Bean名称
     */
    public String getBeanName() {
        return this.beanName;
    }

    /**
     * Return the alias names for the bean, as specified directly for the bean definition.
     *
     * 获取别名数组
     *
     * @return the array of alias names, or {@code null} if none
     */
    public String[] getAliases() {
        return this.aliases;
    }

    /**
     * Expose the bean definition's source object.
     *
     * 获取源
     *
     * @see BeanDefinition#getSource()
     */
    public Object getSource() {
        return this.beanDefinition.getSource();
    }

    /**
     * Determine whether the given candidate name matches the bean name
     * or the aliases stored in this bean definition.
     *
     * 是否匹配名称
     */
    public boolean matchesName(String candidateName) {
        return (candidateName != null &&
                (candidateName.equals(this.beanName) || ObjectUtils.containsElement(this.aliases, candidateName)));
    }


    /**
     * Return a friendly, short description for the bean, stating name and aliases.
     *
     * 获取短描述
     *
     * @see #getBeanName()
     * @see #getAliases()
     */
    public String getShortDescription() {
        StringBuilder sb = new StringBuilder();
        sb.append("Bean definition with name '").append(this.beanName).append("'");
        if (this.aliases != null) {
            sb.append(" and aliases [").append(StringUtils.arrayToCommaDelimitedString(this.aliases)).append("]");
        }
        return sb.toString();
    }

    /**
     * Return a long description for the bean, including name and aliases
     * as well as a description of the contained {@link BeanDefinition}.
     *
     * 获取长描述
     *
     * @see #getShortDescription()
     * @see #getBeanDefinition()
     */
    public String getLongDescription() {
        StringBuilder sb = new StringBuilder(getShortDescription());
        sb.append(": ").append(this.beanDefinition);
        return sb.toString();
    }

    /**
     * This implementation returns the long description. Can be overridden
     * to return the short description or any kind of custom description instead.
     *
     * 转换为字符串
     *
     * @see #getLongDescription()
     * @see #getShortDescription()
     */
    @Override
    public String toString() {
        return getLongDescription();
    }


    /**
     * 判断是否相等
     *
     * @param other
     * @return
     */
    @Override
    public boolean equals(Object other) {
        if (this == other) {
            return true;
        }
        if (!(other instanceof BeanDefinitionHolder)) {
            return false;
        }
        BeanDefinitionHolder otherHolder = (BeanDefinitionHolder) other;
        return this.beanDefinition.equals(otherHolder.beanDefinition) &&
                this.beanName.equals(otherHolder.beanName) &&
                ObjectUtils.nullSafeEquals(this.aliases, otherHolder.aliases);
    }

    /**
     * 哈希值
     *
     * @return
     */
    @Override
    public int hashCode() {
        int hashCode = this.beanDefinition.hashCode();
        hashCode = 29 * hashCode + this.beanName.hashCode();
        hashCode = 29 * hashCode + ObjectUtils.nullSafeHashCode(this.aliases);
        return hashCode;
    }

}
